Skip to content

[SYCL] Add libsycl, a SYCL RT library implementation project #144372

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 17 commits into
base: main
Choose a base branch
from

Conversation

KseniyaTikhomirova
Copy link

This patch introduces libsycl, a SYCL runtime library implementation, as a top-level LLVM runtime project.
SYCL spec: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html

Commit contains the basic folder layout and CMake infrastructure to build a dummy SYCL library.

This is part of the SYCL support upstreaming effort. The relevant RFCs can be found here:

https://discourse.llvm.org/t/rfc-add-full-support-for-the-sycl-programming-model/74080
https://discourse.llvm.org/t/rfc-sycl-runtime-upstreaming/74479

Upcoming PRs:

  • UR offloading library fetch & build
  • partial implementation of sycl::platform: requires offloading layer, requires classes for backend loading & enumeration.

This patch introduces libsycl, a SYCL runtime library implementation, as a top-level LLVM runtime project. It contains the basic folder layout and CMake infrastructure to build a dummy SYCL library.
@KseniyaTikhomirova KseniyaTikhomirova requested a review from a team as a code owner June 16, 2025 15:38
Copy link

Thank you for submitting a Pull Request (PR) to the LLVM Project!

This PR will be automatically labeled and the relevant teams will be notified.

If you wish to, you can add reviewers by using the "Reviewers" section on this page.

If this is not working for you, it is probably because you do not have write permissions for the repository. In which case you can instead tag reviewers by name in a comment by using @ followed by their GitHub username.

If you have received no comments on your PR for a week, you can request a review by "ping"ing the PR by adding a comment “Ping”. The common courtesy "ping" rate is once a week. Please remember that you are asking for valuable time from other developers.

If you have further questions, they may be answered by the LLVM GitHub User Guide.

You can also ask questions in a comment on this PR, on the LLVM Discord or on the forums.

@llvmbot llvmbot added the cmake Build system in general and CMake in particular label Jun 16, 2025
@KseniyaTikhomirova
Copy link
Author

Copy link
Contributor

@philnik777 philnik777 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Disclaimer: I haven't seen the RFCs related to this before and haven't read through them in detail.

I don't know much about SYCL, but I do know quite a bit about libc++ and why we do things in certain ways there. In case you're interested I'd be happy to talk to you about that. Feel free to contact me on Discord, Discourse or E-Mail if you'd like to set up a meeting.

Copy link
Author

@KseniyaTikhomirova KseniyaTikhomirova left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

philnik777 thank you for the review, I really appreciate your comments and guidance.

I replied to all your comments and will provide code updates a bit later.

@Fznamznon Fznamznon added the SYCL https://registry.khronos.org/SYCL label Jun 18, 2025
Signed-off-by: Tikhomirova, Kseniya <[email protected]>
Signed-off-by: Tikhomirova, Kseniya <[email protected]>
@asudarsa asudarsa requested review from asudarsa and removed request for AlexeySachkov June 18, 2025 15:00
Copy link
Contributor

@asudarsa asudarsa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me. Couple of minor nits.

Thanks

@philnik777
Copy link
Contributor

Also, it would be great if we could get the precommit CI running ASAP. IIUC the basic configurations would be:

  • libstdc++/GCC(?)
  • MSVC STL/MSVC
  • libunwind/libc++abi/libc++/Clang
    That should be pretty lean on the CI resources and could probably easily run in the GH-provided runners for now.

Signed-off-by: Tikhomirova, Kseniya <[email protected]>
@KseniyaTikhomirova
Copy link
Author

Also, it would be great if we could get the precommit CI running ASAP. IIUC the basic configurations would be:

  • libstdc++/GCC(?)
  • MSVC STL/MSVC
  • libunwind/libc++abi/libc++/Clang
    That should be pretty lean on the CI resources and could probably easily run in the GH-provided runners for now.

Could you please clarify - is it a blocker for the current PR? Can we add it in the following PRs?

Copy link
Contributor

@philnik777 philnik777 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, it would be great if we could get the precommit CI running ASAP. IIUC the basic configurations would be:

  • libstdc++/GCC(?)
  • MSVC STL/MSVC
  • libunwind/libc++abi/libc++/Clang
    That should be pretty lean on the CI resources and could probably easily run in the GH-provided runners for now.

Could you please clarify - is it a blocker for the current PR? Can we add it in the following PRs?

I don't think it should be a blocker. I'd like it soon though, since it significantly increases confidence that code changes are correct.

@bader bader self-requested a review June 23, 2025 15:40
Signed-off-by: Tikhomirova, Kseniya <[email protected]>
@KseniyaTikhomirova
Copy link
Author

Also, it would be great if we could get the precommit CI running ASAP. IIUC the basic configurations would be:

  • libstdc++/GCC(?)
  • MSVC STL/MSVC
  • libunwind/libc++abi/libc++/Clang
    That should be pretty lean on the CI resources and could probably easily run in the GH-provided runners for now.

Could you please clarify - is it a blocker for the current PR? Can we add it in the following PRs?

I don't think it should be a blocker. I'd like it soon though, since it significantly increases confidence that code changes are correct.

I agree, I will add libsycl build workflow as separate PR.

Copy link
Contributor

@tahonermann tahonermann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @KseniyaTikhomirova! I unresolved one previous comment to follow up some more and added a few other minor comments.

Signed-off-by: Tikhomirova, Kseniya <[email protected]>
@asudarsa
Copy link
Contributor

Hi @KseniyaTikhomirova
Can you please take a look at the merge conflict reported here?
Thanks

Copy link
Contributor

@jhuber6 jhuber6 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be a fine starting point for now, we can fix things later.

@bader
Copy link
Contributor

bader commented Jun 27, 2025

Hi @KseniyaTikhomirova Can you please take a look at the merge conflict reported here? Thanks

@asudarsa, resolved.

Copy link
Contributor

@tahonermann tahonermann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for responding to my prior comments. I added a number of new comments, many of which are minor. I would really like to see some of the differences between windows and Linux/UNIX build differences eliminated; particularly the library naming differences and the "d" debug postfix naming. The default build should produce binaries named appropriately for a LLVM/Clang monorepo build and distribution (which shouldn't differ much between Windows and Linux/UNIX).

@KseniyaTikhomirova KseniyaTikhomirova marked this pull request as draft July 4, 2025 12:33
Signed-off-by: Tikhomirova, Kseniya <[email protected]>
@KseniyaTikhomirova KseniyaTikhomirova marked this pull request as ready for review July 4, 2025 15:49
Signed-off-by: Tikhomirova, Kseniya <[email protected]>
Copy link
Contributor

@tahonermann tahonermann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @KseniyaTikhomirova, this is looking great. I added a few final comments, but will be very happy to approve once we address these.

set(LIB_NAME "sycl")
set(LIB_OUTPUT_NAME "${LIB_NAME}")
if (CMAKE_SYSTEM_NAME STREQUAL Windows)
if (CMAKE_BUILD_TYPE STREQUAL Debug OR CMAKE_MSVC_RUNTIME_LIBRARY STREQUAL MultiThreadedDebugDLL)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to check for "MultiThreadedDebugDLL" specifically? I think the libc++ logic looks appropriate to use here. See

if ((NOT CMAKE_MSVC_RUNTIME_LIBRARY AND uppercase_CMAKE_BUILD_TYPE STREQUAL "DEBUG")
OR (CMAKE_MSVC_RUNTIME_LIBRARY MATCHES "Debug"))
set(LIB_SUFFIX "d")
.

Suggested change
if (CMAKE_BUILD_TYPE STREQUAL Debug OR CMAKE_MSVC_RUNTIME_LIBRARY STREQUAL MultiThreadedDebugDLL)
if ((NOT CMAKE_MSVC_RUNTIME_LIBRARY AND uppercase_CMAKE_BUILD_TYPE STREQUAL "DEBUG")
OR (CMAKE_MSVC_RUNTIME_LIBRARY MATCHES "Debug"))

I know we expect CMAKE_MSVC_RUNTIME_LIBRARY to always be set currently, but this logic will still work as expected if we relax that restriction later.

Copy link
Author

@KseniyaTikhomirova KseniyaTikhomirova Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we don't expect it to be always set. We are ok with cmake default value MultiThreaded$<$CONFIG:Debug:Debug>DLL and handle explicitly set values if needed.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MultiThreadedDebugDLL is the only option that is supported for sycl in Debug mode. Why should we introduce confusion by setting "CMAKE_MSVC_RUNTIME_LIBRARY MATCHES "Debug""?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated this code but left check of full config name "MultiThreadedDebugDLL".
I know that we do a check for "DLL" match a few lines before. Although I want to keep the full name if it is the only option there.
e502190

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I didn't realize that MultiThreadedDebugDLL was the only supported option when building in debug mode. It seems that should be asserted rather than result in the "d" suffix being silently dropped. Should we also ensure that a MT variant is used? How about this?

  if (CMAKE_MSVC_RUNTIME_LIBRARY
      AND (NOT CMAKE_MSVC_RUNTIME_LIBRARY MATCHES "^MultiThreaded.*DLL$"))
    message(FATAL_ERROR "libsycl requires a multi-threaded DLL version of the MSVC CRT.")
  endif()
  if (uppercase_CMAKE_BUILD_TYPE STREQUAL "DEBUG")
    if (NOT CMAKE_MSVC_RUNTIME_LIBRARY STREQUAL "MultiThreadedDebugDLL")
      message(FATAL_ERROR "Debug builds of libsycl require a multi-threaded debug DLL version of the MSVC CRT.")
    endif()
    set(LIB_OUTPUT_NAME "${LIB_OUTPUT_NAME}d")
  endif()

Copy link
Author

@KseniyaTikhomirova KseniyaTikhomirova Jul 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think in our case check for DLL and MultiThreaded*DLL does completely the same. All options start from "MultiThreaded", this change of check brings nothing.
options are:
MultiThreaded
MultiThreadedDLL
MultiThreadedDebug
MultiThreadedDebugDLL

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so with the current impl:
If user sets MultiThreaded, MultiThreadedDebug - user receives error "libsycl requires a DLL version of the MSVC CRT".
Other two options are valid and lead to setting "d" suffix or not.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I forgot that the DLL variants are always multi-threaded.

Hmm, CMake doesn't seem to acknowledge the existence of the single-threaded static CRT library (other than to disable automatically linking with it for at least some targets; https://github.com/Kitware/CMake/blob/master/Modules/Platform/Windows-MSVC.cmake#L203-L205).

The intent is that the "d" suffix is appended if, and only if, the target is linked with a debug version of the MSVC CRT, correct? I had a different understanding of the intent in earlier comments which is why my last suggestion limited appending the "d" suffix to debug builds.

You previously stated:

MultiThreadedDebugDLL is the only option that is supported for sycl in Debug mode.
If the intent is that debug builds of libsycl are always required to link with the (multi-threaded) debug (DLL) variant of the MSVC CRT, then I think a change is warranted to assert that. However, inline with my previous statement about the intent being that "d" is only appended when linking with a debug MSVC CRT variant, then debug builds of libsycl may link with the (multi-threaded) release (DLL) variant of the MSVC CRT. In that case, the code is fine as is.

I still have a slight preference for just checking for a match of "Debug" since I think that best expresses the intent and is consistent with libc++, but I acknowledge that it doesn't change the result. So, your choice how you want to handle this.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"The intent is that the "d" suffix is appended if, and only if, the target is linked with a debug version of the MSVC CRT, correct?"
yes, it is how we do it now.
I would prefer to leave full name (MultiThreadedDebugDLL) since it represents better that SYCL RT is always a DLL, there is no other options.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The required use of a DLL is already assured at this point.

My concern is the "MultiThreaded" part and exact matching. Though CMake doesn't currently acknowledge it, there are additional MSVC CRT implementations; see the MSVC /Qspectre option and the special support for it that exists in MSVS for C++ projects via the "Spectre Mitigation" property. I think it isn't unreasonable that CMake might expose these additional run-time libraries; particularly for the MSBuild/Visual Studio generator. I don't know if the spectre CRT libraries are provided in debug form, but I would rather err on the side of adding the "d" suffix when "Debug" is present in the name than risk not adding it when libsycl is linked with an unknown CRT library.

Signed-off-by: Tikhomirova, Kseniya <[email protected]>
Copy link
Contributor

@tahonermann tahonermann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for all your work on this @KseniyaTikhomirova and for tolerating all of my questions and requests! This looks great!

There is one remaining comment that is unresolved that I just responded to. I'm approving this PR based on my expectation that the code expresses the intent as is. However, if the intent really is that debug builds of libsycl are always required to link with a debug version of the MSVC CRT, then I think an additional change is warranted and we should follow up in that comment thread. But I suspect that isn't actually the intent and we are good here.

Comment on lines 10 to 11
/// This file contains the declaration of the Platform class, which encapsulates
/// a single SYCL platform on which kernel functions may be executed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// This file contains the declaration of the Platform class, which encapsulates
/// a single SYCL platform on which kernel functions may be executed.
/// This file contains the declaration of the SYCL platform class, which
/// encapsulates a single platform on which kernel functions may be executed.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

//===----------------------------------------------------------------------===//
///
/// \file
/// This file is a SYCL2020 standard header file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// This file is a SYCL2020 standard header file.
/// This file is a SYCL 2020 standard header file.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


class _LIBSYCL_EXPORT platform {
public:
/// Constructs a SYCL platform using the default device.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// Constructs a SYCL platform using the default device.
/// Constructs a SYCL platform which contains the default device.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Signed-off-by: Tikhomirova, Kseniya <[email protected]>
Signed-off-by: Tikhomirova, Kseniya <[email protected]>
Copy link
Contributor

@tahonermann tahonermann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it is necessary for files present in the __detail directory to be prefixed with an __; their presence in that directory already signifies that they are not public header files. The include/sycl/__detail/__config.hpp file therefore doesn't need the __ prefix. __platform.hpp should still be named with a __ prefix though since it is not a public header file and is not located in a __ prefixed directory. This is consistent with what libc++ does; see https://github.com/llvm/llvm-project/tree/main/libcxx/include.

The number of header files that are prefixed with an __ can be reduced by placing all non-public header files in some __ prefixed directory; perhaps the __detail directory or split in some fashion. For example, a header file like platform.hpp that implements a public facing interface specified in the SYCL specification could be placed in a __implementation or __impl directory with the __detail directory reserved for things like the DPC++ program manager that really implementation detail. I don't have strong opinions how the files are structured so long as non-public header files are either in a __ prefixed directory or themselves have a __ prefix (but not both).

@tahonermann
Copy link
Contributor

tahonermann commented Jul 14, 2025

I think it would be useful to also add the include/CL directory and the (deprecated) include/CL/sycl.hpp header file to fully flush out the header file organization. https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:headers-and-namespaces.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cmake Build system in general and CMake in particular SYCL https://registry.khronos.org/SYCL
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants